<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Advanced Topics
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot039.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot037.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot041.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc95">7.3</A>&nbsp;&nbsp;Advanced Topics</H2><UL>
<LI><A HREF="umsroot040.html#toc57">Solving Name Conflicts</A>
<LI><A HREF="umsroot040.html#toc58">Qualified Access via :/2</A>
<LI><A HREF="umsroot040.html#toc59">Reexport - Making Modules from Modules</A>
<LI><A HREF="umsroot040.html#toc60">Modules and Source Files</A>
<LI><A HREF="umsroot040.html#toc61">Tools and Caller Modules</A>
<LI><A HREF="umsroot040.html#toc62">Lookup Module vs Caller Module</A>
<LI><A HREF="umsroot040.html#toc63">The Module Interface</A>
<LI><A HREF="umsroot040.html#toc64">Module-related Predicate Properties</A>
</UL>

<A NAME="toc57"></A>
<H3 CLASS="subsection"><A NAME="htoc96">7.3.1</A>&nbsp;&nbsp;Solving Name Conflicts</H3>

Name conflicts occur in two flavours:
<A NAME="@default331"></A>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>Import/Import conflict:</B><DD CLASS="dd-description">
 this is the case when two or more imported modules provide a
 predicate of the same name.
<DT CLASS="dt-description"><B>Import/Local conflict:</B><DD CLASS="dd-description">
 this is the case when a local (or exported) predicate has the
 same name as a predicate provided from an imported module.
</DL>
Conflicts of the first type are accepted silently by the system as
long as there is no reference to the conflict predicate. Only when an attempt
<A NAME="@default332"></A>
is made to access the conflict predicate is an error raised.
The conflict can be resolved by explicitly importing one of the versions, e.g.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- lib(ria).                 % exports #&gt;= / 2
:- lib(eplex).               % exports #&gt;= / 2
:- import (#&gt;=)/2 from ria.  % resolves the conflict
</PRE></BLOCKQUOTE>
Alternatively, the conflict can remain unresolved and qualified access can
be used whenever the predicates are referred to (see&nbsp;<A HREF="#qualifiedaccess">7.3.2</A>).<BR>
<BR>
Conflicts of the second type give rise to an error or warning message
<A NAME="@default333"></A>
<A NAME="@default334"></A>
when the compiler encounters the local (re)definition. To avoid that,
an explicit
<A HREF="../bips/kernel/modules/local-1.html"><B>local/1</B></A><A NAME="@default335"></A>
declaration has to be used:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local write/1.
write(X) :-   % my own version of write/1
   ...
</PRE></BLOCKQUOTE>
Note that the <A HREF="../bips/kernel/modules/local-1.html"><B>local/1</B></A><A NAME="@default336"></A>-declaration
must occur textually before any use of the predicate inside the module.<BR>
<BR>
<A NAME="toc58"></A>
<H3 CLASS="subsection"><A NAME="htoc97">7.3.2</A>&nbsp;&nbsp;Qualified Access via :/2</H3>
<A NAME="qualifiedaccess"></A>
<A NAME="@default337"></A>

Normally, it is convenient to import predicates which are needed.
By importing, they become <B>visible</B> and can be used within
<A NAME="@default338"></A>
the module in the same way as local definitions.
However, sometimes it is preferable to explicitly specify from
which module a definition is meant to be taken. This is the case for
example when multiple versions of the predicate are needed,
or when the presence of a local definition makes it impossible
to import a predicate of the same name from elsewhere.
A call with explicit module qualification is done using
<A HREF="../bips/kernel/control/N-2.html"><B>: /2</B></A><A NAME="@default339"></A>
and looks like this:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
lists:print_list([1,2,3])
</PRE></BLOCKQUOTE>
Here, the module where the definition of print_list/1 is looked up
(the <B>lookup module</B>) is explicitly specified. To call print_list/1
like this, it is not necessary to make print_list/1 visible.
The only requirement is that it is exported (or reexported) from
the module <TT>lists</TT>.<BR>
<BR>
Note that, if the called predicate is in operator notation, it will
often be necessary to use brackets, e.g. in
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
..., ria:(X #&gt;= Y), ...
</PRE></BLOCKQUOTE>
The <A HREF="../bips/kernel/control/N-2.html"><B>: /2</B></A><A NAME="@default340"></A> primitive can be used to resolve import conflicts,
i.e. the case where the same name is exported from more than one
module and both are needed. In this case, none of the conflicting
predicates is imported - an attempt to call the unqualified predicate
raises an error.
The solution is to qualify every reference with the module name:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- lib(ria).    % exports #&gt;= / 2
:- lib(eplex).  % exports #&gt;= / 2

    ..., ria:(X #&gt;= Y), ...
    ..., eplex:(X #&gt;= Y), ...
</PRE></BLOCKQUOTE>
Another case is the situation that a module wants to define a
predicate of a given name but at the same time use a predicate
of the same name from another module. It is not possible to
import the predicate because of the name conflict with the local
definition. Explicit qualification must be used instead:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- lib(lists).

print_list(List) :-
        writeln("This is the list"),
        lists:print_list(List).
</PRE></BLOCKQUOTE>
A more unusual feature, which is however very appropriate for
constraint programming, is the possibility to call several versions
of the same predicate by specifying several lookup modules:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
    ..., [ria,eplex]:(X #&gt;= Y), ...
</PRE></BLOCKQUOTE>
which has exactly the same meaning as
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
    ..., ria:(X #&gt;= Y), eplex:(X #&gt;= Y), ...
</PRE></BLOCKQUOTE>
Note that the modules do not have to be known at compile time, i.e. it
is allowed to write code like
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
    after(X, Y, Solver) :-
        Solver:(X #&gt;= Y).
</PRE></BLOCKQUOTE>
However, this is likely to be less efficient because it prevents
compile-time optimizations.<BR>
<BR>
<A NAME="toc59"></A>
<H3 CLASS="subsection"><A NAME="htoc98">7.3.3</A>&nbsp;&nbsp;Reexport - Making Modules from Modules</H3>

To allow more flexibility in the design of module interfaces, and to
avoid duplication of definitions, it is possible to re-export definitions.
A reexport is an import combined with an export.
That means that a reexported definition becomes visible inside the
reexporting module and is at the same time exported again.
A user of a module's interface sees no difference between
exported and reexported definitions<SUP><A NAME="text5" HREF="umsroot037.html#note5">2</A></SUP>.<BR>
<BR>
There are 3 forms of the
<A HREF="../bips/kernel/modules/reexport-1.html"><B>reexport/1</B></A><A NAME="@default341"></A>
directive. To reexport the complete
module interface of another module, use
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- reexport amodule.
</PRE></BLOCKQUOTE>
To reexport only an explicitly enumerated selection, use
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- reexport p/1,q/2 from amodule.
</PRE></BLOCKQUOTE>
To reexport everything except some explicitly enumerated items, use
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- reexport amodule except p/2,q/3.
</PRE></BLOCKQUOTE>
These facilities make it possible to extend, modify, restrict or
combine modules into new modules, as illustrated in figure&nbsp;<A HREF="#reexport">7.1</A>. 
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<IMG SRC="umsroot008.gif">
</DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 7.1: Making modules from modules with reexport</DIV><BR>
<BR>

<A NAME="reexport"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<A NAME="toc60"></A>
<H3 CLASS="subsection"><A NAME="htoc99">7.3.4</A>&nbsp;&nbsp;Modules and Source Files</H3>
<A NAME="@default342"></A>

When a source file contains no module directives, it becomes part of
the module from which its compilation was invoked. This makes it
possible to write small programs without caring about modules. 
However, serious applications should be structured into modules. <BR>
<BR>
Often it is the most appropriate to have one file per module and to
have the file name match the module name.<BR>
<BR>
It is however possible to have several modules in one file, e.g. a
main module and one or more auxiliary modules - in that
case the name of the main module should match the filename.
Every module-directive in the file marks the end of the previous
module and the start of the next one.<BR>
<BR>
It is also possible to spread the contents of a module over several
files. In this case, there should be a main file whose filename
matches the module name, and the other files should be referenced
from the main file using the <A HREF="../bips/kernel/directives/include-1.html"><B>include/1</B></A><A NAME="@default343"></A> directive, e.g.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- module(bigmodule).
:- include(part1).
:- include(part2).
</PRE></BLOCKQUOTE>
<A NAME="toc61"></A>
<H3 CLASS="subsection"><A NAME="htoc100">7.3.5</A>&nbsp;&nbsp;Tools and Caller Modules</H3>


<H4 CLASS="subsubsection">Tools</H4>
<A NAME="@default344"></A>
<A NAME="@default345"></A>
<A NAME="tools"></A>
There are predicates in a modular system that need to know from which
module they were called (since this may be different from the module
in which they were defined).
<A NAME="@default346"></A>
The most common case is where a predicate is a meta-predicate,
i.e. a predicate that has another goal or predicate name as an argument.
Other cases are I/O predicates - they need to be executed in a
certain module context in order to obey the correct syntax of this module.
In ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, such predicates that need to know their caller module
are called <B>tool</B> predicates<SUP><A NAME="text6" HREF="umsroot037.html#note6">3</A></SUP>.<BR>
<BR>
Tool predicates must be declared. As a consequence, the system will
automatically add a <B>caller module</B> argument whenever such a tool
predicate is called.<BR>
<BR>
Consider for example a predicate that calls another predicate twice.
<A NAME="@default347"></A>
The naive version of this predicate looks like
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
twice(Goal) :-
    call(Goal),
    call(Goal).
</PRE></BLOCKQUOTE>
As long as no modules are involved, this works fine.
Now consider the situation where the definition of twice/1 and a
call of twice/1 are in two different modules:
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
:- module(stuff).
:- export twice/1.
twice(Goal) :-
    call(Goal),
    call(Goal).

:- module(main).
:- import stuff.

top :- twice(hello).

hello :- writeln(hi).
</PRE></BLOCKQUOTE>
This will not work because hello/0 is only visible in module main
and an attempt to call it from within twice/1 in module stuff will
raise an error. The solution is to declare twice/1 as a tool and
change the code as follows:
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
:- module(stuff).
:- export twice/1.
:- tool(twice/1, twice/2).
twice(Goal, Module) :-
    call(Goal)@Module,
    call(Goal)@Module.
</PRE></BLOCKQUOTE>
What happens now is that the call to twice/1 in module main
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
..., twice(hello), ...
</PRE></BLOCKQUOTE>
is effectively replaced by the system with a call to twice/2 where
the additional argument is the module in which the call occurs:
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
..., twice(hello, main), ...
</PRE></BLOCKQUOTE>
This caller module is then used by twice/2 to execute
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
..., call(hello)@main, ...
</PRE></BLOCKQUOTE>
The 
<A HREF="../bips/kernel/control/A-2.html"><B>call(Goal)@Module</B></A>
<A NAME="@default348"></A> construct means that the call is supposed to happen
<EM>in the context</EM> of module main.<BR>
<BR>
The debugger trace shows what happens:
<BLOCKQUOTE CLASS="quote"> <PRE CLASS="verbatim">
[main 5]: top.
  (1) 1 CALL  top
  (2) 2 CALL  twice(hello)
  (3) 3 CALL  twice(hello, main)
  (4) 4 CALL  call(hello) @ main
  (5) 5 CALL  call(hello)
  (6) 6 CALL  hello
S (7) 7 CALL  writeln(hi)
hi
S (7) 7 EXIT  writeln(hi)
  (6) 6 EXIT  hello
  ...
</PRE></BLOCKQUOTE>
One complication that can arise when you use tools is that the compiler
must know that a predicate is a tool in order to properly compile
a call to the tool.
If the call occurs textually before the tool
declaration, this will therefore give rise to an
<B>inconsistent tool redefinition</B> error.
The
<A HREF="../bips/kernel/modules/tool-2.html"><B>tool/2</B></A><A NAME="@default349"></A>
declaration must therefore occur before any call to the tool.<BR>
<BR>

<H4 CLASS="subsubsection">System Tools</H4>
<A NAME="@default350"></A>
Many of the system built-in predicates are in fact tools, e.g.
<A HREF="../bips/kernel/ioterm/read-1.html"><B>read/1</B></A><A NAME="@default351"></A>,
<A HREF="../bips/kernel/ioterm/write-1.html"><B>write/1</B></A><A NAME="@default352"></A>,
<A HREF="../bips/kernel/record/record-2.html"><B>record/2</B></A><A NAME="@default353"></A>,
<A HREF="../bips/kernel/compiler/compile-1.html"><B>compile/1</B></A><A NAME="@default354"></A>, etc.
All predicates which handle modular items must be tools
so that they know from which module they have been called.
In case that the built-in predicate has to be executed in
a different module (this is very often the case inside
user tool predicates), the 
<A HREF="../bips/kernel/control/A-2.html"><B>@ /2</B></A><A NAME="@default355"></A>
construct must be used, e.g.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
current_predicate(P) @ SomeModule
</PRE></BLOCKQUOTE>
<A NAME="toc62"></A>
<H3 CLASS="subsection"><A NAME="htoc101">7.3.6</A>&nbsp;&nbsp;Lookup Module vs Caller Module</H3>
<A NAME="@default356"></A>
<A NAME="@default357"></A>

The following table summarises the different call patterns with and
without module specifications.
There are only two basic rules to remember:
<UL CLASS="itemize"><LI CLASS="li-itemize">
<A HREF="../bips/kernel/control/N-2.html"><B>: /2</B></A><A NAME="@default358"></A>
	specifies the <B>lookup module</B> (to find the definition)
<LI CLASS="li-itemize"><A HREF="../bips/kernel/control/A-2.html"><B>@ /2</B></A>
<A NAME="@default359"></A> 
	specifies the <B>caller module</B> (to know the context)
</UL><BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left>Call inside module(m)	</TD>
<TD VALIGN=top ALIGN=left>Module where definition of twice/1 is looked up
	</TD>
<TD VALIGN=top ALIGN=left>Caller module argument added to twice/1</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>..., twice(X), ...		</TD>
<TD VALIGN=top ALIGN=left>m</TD>
<TD VALIGN=top ALIGN=left>m</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>..., lm : twice(X), ...		</TD>
<TD VALIGN=top ALIGN=left>lm</TD>
<TD VALIGN=top ALIGN=left>m</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>..., twice(X) @ cm, ...		</TD>
<TD VALIGN=top ALIGN=left>m</TD>
<TD VALIGN=top ALIGN=left>cm</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>..., lm : twice(X) @ cm, ...	</TD>
<TD VALIGN=top ALIGN=left>lm</TD>
<TD VALIGN=top ALIGN=left>cm</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>..., call(twice(X)) @ cm, ...	</TD>
<TD VALIGN=top ALIGN=left>cm</TD>
<TD VALIGN=top ALIGN=left>cm</TD>
</TR></TABLE><BR>
<A NAME="toc63"></A>
<H3 CLASS="subsection"><A NAME="htoc102">7.3.7</A>&nbsp;&nbsp;The Module Interface</H3>
The primitive 
<A HREF="../bips/kernel/modules/current_module-1.html"><B>current_module/1</B></A><A NAME="@default360"></A>
can be used to check for the existence of a module, or to enumerate
all currently defined modules.<BR>
<BR>
Further details about existing modules can be retrieved using
<A NAME="@default361"></A>
<A HREF="../bips/kernel/modules/get_module_info-3.html"><B>get_module_info/3</B></A><A NAME="@default362"></A>,
in particular information about the module's interface, what other
modules it uses and whether it is locked (see&nbsp;<A HREF="umsroot041.html#locking">7.4.4</A>).<BR>
<BR>
<A NAME="toc64"></A>
<H3 CLASS="subsection"><A NAME="htoc103">7.3.8</A>&nbsp;&nbsp;Module-related Predicate Properties</H3>
Information about a predicate's properties can be retrieved using the 
<A NAME="@default363"></A>
<A HREF="../bips/kernel/compiler/get_flag-3.html"><B>get_flag/3</B></A><A NAME="@default364"></A> primitive
or printed using <A HREF="../bips/kernel/env/pred-1.html"><B>pred/1</B></A><A NAME="@default365"></A>.
The module-related predicate properties are
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>defined</B><DD CLASS="dd-description">
	(on/off) indicates whether code for the predicate has already
	been compiled. If not, only a declaration was encountered.
<DT CLASS="dt-description"><B>definition_module</B><DD CLASS="dd-description">
	(an atom) the module where the predicate is defined.
<DT CLASS="dt-description"><B>visibility</B><DD CLASS="dd-description">
	(local/exported/reexported/imported) indicates the visibility
	of the predicate in the caller module.
<DT CLASS="dt-description"><B>tool</B><DD CLASS="dd-description">
	(on/off) indicates whether the predicate has been declared a tool.
</DL>
For tool predicates, 
<A HREF="../bips/kernel/modules/tool_body-3.html"><B>tool_body/3</B></A><A NAME="@default366"></A>
can be used to retrieve the predicate it maps to when the module
argument is added.<BR>
<BR>
To get information about a predicate visible in a different module,
use for instance
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
    get_flag(p/3, visibility, V) @ othermodule
</PRE></BLOCKQUOTE>
<HR>
<A HREF="umsroot039.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot037.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot041.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
